.\" $Id: PAPI_start.3,v 1.16 2004/10/04 03:21:11 jthomas Exp $
.TH PAPI_start 3 "September, 2004" "PAPI Programmer's Reference" "PAPI"

.SH NAME
PAPI_start \- start counting hardware events in an event set
.LP
PAPI_stop \- stop counting hardware events in an event set

.SH SYNOPSIS
.B C Interface
.nf
.B #include <papi.h>
.BI "int\ PAPI_start(int " EventSet ");"
.BI "int\ PAPI_stop(int " EventSet ", long_long *" values ");"
.fi
.B Fortran Interface
.nf
.B #include "fpapi.h"
.BI PAPIF_start(C_INT\  EventSet,\  C_INT\  check )
.BI PAPIF_stop(C_INT\  EventSet,\  C_LONG_LONG(*)\  values,\  C_INT\  check )
.fi

.SH DESCRIPTION
.B PAPI_start
starts counting all of the hardware events contained in the previously
defined EventSet.
All counters are implicitly set to zero before counting.
.LP
.B PAPI_stop
halts the counting of a previously defined event set and the counter values
contained in that EventSet are copied into the values array
.LP
These calls assume an initialized PAPI library and a properly
added event set.

.SH ARGUMENTS
.I "EventSet"
--  an integer handle for a PAPI event set as created by
.BR "PAPI_create_eventset" (3)
.LP
.I *values
-- an array to hold the counter values of the counting events

.SH RETURN VALUES
On success, this function returns
.B "PAPI_OK."
 On error, a non-zero error code is returned.

.SH ERRORS
.TP
.B "PAPI_EINVAL"
One or more of the arguments is invalid.
.TP
.B "PAPI_ESYS"
A system or C library call failed inside PAPI, see the 
.I "errno"
variable.
.TP
.B "PAPI_ENOEVST"
The EventSet specified does not exist.
.TP
.B "PAPI_EISRUN"
The EventSet is currently counting events.
.BR ""  ( "PAPI_start() " only)
.TP
.B "PAPI_ENOTRUN"
The EventSet is currently not running.
.BR "" ( "PAPI_stop() " only)
.TP
.B "PAPI_ECNFLCT"
The underlying counter hardware can not count this event and other events
in the EventSet simultaneously.
.BR "" ( "PAPI_start() " only)
.TP
.B "PAPI_ENOEVNT"
The PAPI preset is not available on the underlying hardware. 

.SH EXAMPLES
.nf         
.if t .ft CW
  if (PAPI_create_eventset(&EventSet) != PAPI_OK)
    handle_error(1);

  /* Add Total Instructions Executed to our EventSet */
  if (PAPI_add_event(EventSet, PAPI_TOT_INS) != PAPI_OK)
    handle_error(1);

  /* Start counting */
  if (PAPI_start(EventSet) != PAPI_OK)
    handle_error(1);

  poorly_tuned_function();

  if (PAPI_stop(EventSet, values) != PAPI_OK)
    handle_error(1);

  printf("%lld\\n",values[0]);
.if t .ft P
.fi         

.SH BUGS
These functions have no known bugs.

.SH SEE ALSO
.BR PAPI_create_eventset "(3), " PAPI_add_event "(3), " 
.BR PAPI "(3), " PAPIF "(3)"
